ngAnimate
( directive in module ng
)
The ngAnimate
directive works as an attribute that is attached alongside pre-existing directives.
It effects how the directive will perform DOM manipulation. This allows for complex animations to take place
without burdening the directive which uses the animation with animation details. The built in directives
ngRepeat
, ngInclude
, ngSwitch
, ngShow
, ngHide
and ngView
already accept ngAnimate
directive.
Custom directives can take advantage of animation through $animator service
.
Below is a more detailed breakdown of the supported callback events provided by pre-exisitng ng directives:
Directive | Supported Animations |
---|---|
enter, leave and move |
|
enter and leave |
|
enter and leave |
|
enter and leave |
|
show and hide |
You can find out more information about animations upon visiting each directive page.
Below is an example of a directive that makes use of the ngAnimate attribute:
<!-- you can also use data-ng-animate, ng:animate or x-ng-animate as well --> <ANY ng-directive ng-animate="{event1: 'animation-name', event2: 'animation-name-2'}"></ANY> <!-- you can also use a short hand --> <ANY ng-directive ng-animate=" 'animation' "></ANY> <!-- which expands to --> <ANY ng-directive ng-animate="{ enter: 'animation-enter', leave: 'animation-leave', ...}"></ANY> <!-- keep in mind that ng-animate can take expressions --> <ANY ng-directive ng-animate=" computeCurrentAnimation() "></ANY>
The event1
and event2
attributes refer to the animation events specific to the directive that has been assigned.
Keep in mind that if an animation is running, no child element of such animation can also be animated.
By default, ngAnimate attaches two CSS3 classes per animation event to the DOM element to achieve the animation. It is up to you, the developer, to ensure that the animations take place using cross-browser CSS3 transitions. All that is required is the following CSS code:
<style type="text/css"> /* The animate-enter prefix is the event name that you have provided within the ngAnimate attribute. */ .animate-enter-setup { -webkit-transition: 1s linear all; /* Safari/Chrome */ -moz-transition: 1s linear all; /* Firefox */ -ms-transition: 1s linear all; /* IE10 */ -o-transition: 1s linear all; /* Opera */ transition: 1s linear all; /* Future Browsers */ /* The animation preparation code */ opacity: 0; } /* Keep in mind that you want to combine both CSS classes together to avoid any CSS-specificity conflicts */ .animate-enter-setup.animate-enter-start { /* The animation code itself */ opacity: 1; } </style> <div ng-directive ng-animate="{enter: 'animate-enter'}"> </div>
Upon DOM mutation, the setup class is added first, then the browser is allowed to reflow the content and then, the start class is added to trigger the animation. The ngAnimate directive will automatically extract the duration of the animation to determine when the animation ends. Once the animation is over then both CSS classes will be removed from the DOM. If a browser does not support CSS transitions then the animation will start and end immediately resulting in a DOM element that is at it's final state. This final state is when the DOM element has no CSS animation classes surrounding it.
In the event that you do not want to use CSS3 animations or if you wish to offer animations to browsers that do not yet support them, then you can make use of JavaScript animations defined inside ngModule.
var ngModule = angular.module('YourApp', []); ngModule.animation('animate-enter', function() { return { setup : function(element) { //prepare the element for animation element.css({ 'opacity': 0 }); var memo = "..."; //this value is passed to the start function return memo; }, start : function(element, done, memo) { //start the animation element.animate({ 'opacity' : 1 }, function() { //call when the animation is complete done() }); } } });
As you can see, the JavaScript code follows a similar template to the CSS3 animations. Once defined, the animation can be used in the same way with the ngAnimate attribute. Keep in mind that, when using JavaScript-enabled animations, ngAnimate will also add in the same CSS classes that CSS-enabled animations do (even if you're using JavaScript animations) to animated the element, but it will not attempt to find any CSS3 transition duration value. It will instead close off the animation once the provided done function is executed. So it's important that you make sure your animations remember to fire off the done function once the animations are complete.
<ANY ng-animate="{expression}"> ... </ANY>as class
<ANY class="ng-animate: {expression};"> ... </ANY>
ngAnimate – {expression} –
Used to configure the DOM manipulation animations.